home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / libs / maestixlib.lha / Maestix / maestix-e.adoc < prev    next >
Text File  |  1995-03-29  |  13KB  |  472 lines
  1. TABLE OF CONTENTS
  2.  
  3. (V35) maestix.library/AllocMaestro
  4. (V36) maestix.library/FlushReceive
  5. (V36) maestix.library/FlushTransmit
  6. (V35) maestix.library/FreeMaestro
  7. (V35) maestix.library/GetStatus
  8. (V35) maestix.library/ReceiveData
  9. (V35) maestix.library/SetMaestro
  10. (V38) maestix.library/StartRealtime
  11. (V38) maestix.library/StopRealtime
  12. (V35) maestix.library/TransmitData
  13.  
  14. maestix.library/AllocMaestro                     maestix.library/AllocMaestro
  15.  
  16.    NAME
  17.     AllocMaestro -- Allocates the Maestro soundcard (V35)
  18.  
  19.    SYNOPSIS
  20.     ^MaestroBase = AllocMaestro (^Tags)
  21.         D0.l                      A0.l
  22.  
  23.    FUNCTION
  24.     This function allocates the Maestro soundcard and gives
  25.     exclusive access to the client.
  26.  
  27.     The default settings after AllocMaestro() are:
  28.  
  29.         Input is INPUT_STD,
  30.         Output is OUTPUT_BYPASS,
  31.         Studio mode is turned off,
  32.         Copy protection is turned off,
  33.         Emphasis is turned off,
  34.         Source is DAT,
  35.         Rate is 48kHz,
  36.         Validity is true,
  37.         the UDBs are reset.
  38.  
  39.    INPUTS
  40.     Tags            Reserved for future options. Currently always
  41.             NULL or a pointer to TAG_DONE.
  42.  
  43.    RESULTS
  44.     MaestroBase     Pointer to the MaestroBaseStruct (private) or
  45.             NULL, if the card has already been allocated
  46.             or is not present.
  47.  
  48.    NOTES
  49.     This function must be used from DOS process only!
  50.  
  51.    SEE ALSO
  52.     FreeMaestro()
  53.  
  54.    BUGS
  55.     This function cannot prevent the MacroSystem programs (MaestroBR
  56.     and Samplitude) from using Maestro, too.
  57.  
  58.     This function tries to detect if such a program is currently
  59.     using the card, and does not allow a second allocation. But
  60.     this try may fail, so be aware! Since some old Maestix failed
  61.     even in the case the card was not allocated, this test was
  62.     removed in V37. Use AllocMstx and FreeMstx to avoid this
  63.     problem.
  64.  
  65. maestix.library/FlushReceive                     maestix.library/FlushReceive
  66.  
  67.    NAME
  68.     FlushReceive -- Stops receiver and replies all messages (V36)
  69.  
  70.    SYNOPSIS
  71.     FlushReceive (^MaestroBase)
  72.                A0.l
  73.  
  74.    FUNCTION
  75.     This function stops the receiver.
  76.  
  77.     All messages sent to Maestix by ReceiveData() are replied.
  78.  
  79.    INPUTS
  80.     MaestroBase     Pointer to MaestroBaseStruct from AllocMaestro().
  81.  
  82.    RESULTS
  83.  
  84.    NOTES
  85.  
  86.    SEE ALSO
  87.     FlushTransmit(), ReceiveData()
  88.  
  89.    BUGS
  90.  
  91. maestix.library/FlushTransmit                   maestix.library/FlushTransmit
  92.  
  93.    NAME
  94.     FlushTransmit -- Stops transmission and replies all messages (V36)
  95.  
  96.    SYNOPSIS
  97.     FlushTransmit (^MaestroBase)
  98.                A0.l
  99.  
  100.    FUNCTION
  101.     This function stops the transmitter.
  102.  
  103.     All messages sent to Maestix by TransmitData() are replied.
  104.  
  105.    INPUTS
  106.     MaestroBase     Pointer to MaestroBaseStruct from AllocMaestro().
  107.  
  108.    RESULTS
  109.  
  110.    NOTES
  111.  
  112.    SEE ALSO
  113.     FlushReceive(), TransmitData()
  114.  
  115.    BUGS
  116.  
  117. maestix.library/FreeMaestro                       maestix.library/FreeMaestro
  118.  
  119.    NAME
  120.     FreeMaestro -- Frees the Maestro soundcard (V35)
  121.  
  122.    SYNOPSIS
  123.     FreeMaestro (^MaestroBase)
  124.              A0.l
  125.  
  126.    FUNCTION
  127.     The client must use this function to free the Maestro when he
  128.     does not need it any more.
  129.  
  130.     All messages previously sent to Maestix will be replied. The
  131.     FIFOs are cleared, the card is reset and switches to bypass
  132.     mode.
  133.  
  134.    INPUTS
  135.     MaestroBase     Pointer to MaestroBaseStruct from AllocMaestro().
  136.  
  137.    RESULTS
  138.  
  139.    NOTES
  140.     This function must be used from DOS process only!
  141.  
  142.    SEE ALSO
  143.     AllocMaestro()
  144.  
  145.    BUGS
  146.  
  147. maestix.library/GetStatus                           maestix.library/GetStatus
  148.  
  149.    NAME
  150.     GetStatus -- Returns the current card status (V35)
  151.  
  152.    SYNOPSIS
  153.     Status = GetStatus (^MaestroBase,info type)
  154.      D0.l                    A0.l      D0.l
  155.  
  156.    FUNCTION
  157.     The status fitting to the info type will be returned.
  158.  
  159.    INPUTS
  160.     MaestroBase     Pointer to MaestroBaseStruct from AllocMaestro().
  161.     info type       Type code (MSTAT_...) of the status value that
  162.             should be returned.
  163.  
  164.    RESULTS
  165.     Status          The result of the status query.
  166.  
  167.    NOTES
  168.     The following info types are existing:
  169.  
  170.     MSTAT_TFIFO     Status of transmitter FIFO
  171.              - FIFO_Off     -> transmitter is off
  172.              - FIFO_Running -> transmission is running
  173.              - FIFO_Error   -> an error occured since
  174.                        last query
  175.  
  176.     MSTAT_RFIFO     Status of receiver FIFO
  177.              - FIFO_Off     -> receiver is off
  178.              - FIFO_Running -> receiver is running
  179.              - FIFO_Error   -> an error occured since
  180.                        last query
  181.  
  182.     MSTAT_Signal    checks the signal at the current INPUT.
  183.             FALSE if there is no signal (BOOL).
  184.  
  185.     MSTAT_Emphasis  returns TRUE if the input signal has been
  186.             recorded using emphasis. (BOOL)
  187.  
  188.     MSTAT_DATsrc    returns TRUE if the data source is a DAT
  189.             or DCC recorder. (BOOL)
  190.  
  191.     MSTAT_CopyProh  returns TRUE if copy protection is requested
  192.             from source. It is not possible to detect
  193.             if it is an original or a copy! (BOOL)
  194.  
  195.     MSTAT_Rate      returns input rate (ULONG).
  196.  
  197.     MSTAT_UDB       [V37] returns the current UDBs (UBYTE).
  198.  
  199.    SEE ALSO
  200.  
  201.    BUGS
  202.  
  203. maestix.library/ReceiveData                       maestix.library/ReceiveData
  204.  
  205.    NAME
  206.     ReceiveData -- Receives data into a message (V35)
  207.  
  208.    SYNOPSIS
  209.     ReceiveData (^MaestroBase, ^DataMessage)
  210.             A0.l           A1.l
  211.  
  212.    FUNCTION
  213.     The client has to fill out a DataMessage structure with a
  214.     reply port, a pointer to a data buffer and the size of this
  215.     buffer.
  216.  
  217.     This message is queued internally. If the receiver has not
  218.     been started yet, this function will activate it.
  219.  
  220.     The buffer space get filled with the incoming data and will
  221.     be replied to the declared reply port when the space has been
  222.     filled completely.
  223.  
  224.     If there are no more messages in the queue, the receiver
  225.     will be stopped automatically, and an error is reported.
  226.  
  227.     The buffer is filled with signed words. The first word always
  228.     belongs to the left channel, the second to the right, and so
  229.     on.
  230.  
  231.    INPUTS
  232.     MaestroBase     Pointer to MaestroBase Struct from AllocMaestro().
  233.     Message         Pointer to a system message with a pointer to
  234.             a buffer space for incoming data.
  235.  
  236.    RESULTS
  237.  
  238.    NOTES
  239.     The buffer space must be public memory. Its address must be
  240.     longword aligned and its length must be aligned to 1024.
  241.  
  242.    SEE ALSO
  243.     TransmitData(), FlushReceive()
  244.  
  245.    BUGS
  246. maestix.library/SetMaestro                         maestix.library/SetMaestro
  247.  
  248.    NAME
  249.     SetMaestro -- Sets the Maestro parameters (V35)
  250.  
  251.    SYNOPSIS
  252.     SetMaestro (^MaestroBase, ^Tags)
  253.             A0.l       A1.l
  254.  
  255.    FUNCTION
  256.     The card parameters are changed by the tags.
  257.  
  258.    INPUTS
  259.     MaestroBase     Pointer to MaestroBase Struct from AllocMaestro().
  260.     Tags            Tag list with the changes
  261.  
  262.    RESULTS
  263.  
  264.    TAGS
  265.     MTAG_Input      (ULONG) selects the input that shall be used.
  266.             Default is INPUT_STD, which is the input
  267.             selected by SetMstx. INPUT_OPTICAL and
  268.             INPUT_COAXIAL select the corresponding input.
  269.             INPUT_SRC48K selects the internal 48kHz source.
  270.  
  271.     MTAG_Output     (ULONG) selects the data source for the Maestro
  272.             output. Default is OUTPUT_BYPASS which leads
  273.             the incoming data directly to the output.
  274.             OUTPUT_INPUT decodes the input signal and
  275.             encodes it with new channel status bits and
  276.             user data bits. OUTPUT_FIFO encodes the trans-
  277.             ferred data to output.
  278.  
  279.     MTAG_SetCSB     (ULONG) The 32 bit will be put into the channel
  280.             status bits directly. This tag should be used
  281.             only exceptional.
  282.  
  283.     MTAG_SetUDB     (ULONG) The 32 bit will be put into the user
  284.             data bits.
  285.  
  286.     MTAG_Studio     (BOOL) The studio mode is selected if this
  287.             tag is TRUE, otherwise the custom mode is
  288.             selected. Defaults to FALSE.
  289.  
  290.     MTAG_CopyProh   (ULONG) CPROH_OFF turns the copy protection
  291.             off. CPROH_ON enables the copy protection,
  292.             but one single digital copy can be made.
  293.             CPROH_PROHIBIT turns the copy protection on;
  294.             the signal cannot be recorded. CPROH_INPUT
  295.             turns the copy protection on or off correspon-
  296.             ding to the input signal. Default is CPROH_OFF.
  297.  
  298.     MTAG_Emphasis   (ULONG) EMPH_OFF turns emphasis off. EMPH_50us
  299.             (= EMPH_ON) turns standard emphasis on. When
  300.             using studio mode, EMPH_CCITT and EMPH_MANUAL
  301.             can be selected, too. EMPH_INPUT chooses the
  302.             emphasis corresponding to the input signal.
  303.             Default is EMPH_OFF.
  304.  
  305.     MTAG_Source     (ULONG) selects the source category code.
  306.             Default is SRC_DAT. Other codes are SRC_DSR,
  307.             SRC_CD, SRC_ADCONV and SRC_INSTR. SRC_INPUT
  308.             selects SRC_DAT or SRC_CD, corresponding to
  309.             the input signal.
  310.  
  311.     MTAG_Rate       (ULONG) selects the rate. RATE_48000 is default,
  312.             RATE_44100, RATE_32000 and RATE_48000MANU are
  313.             possible, too. RATE_INPUT chooses a rate
  314.             corresponding to the input signal.
  315.  
  316.     MTAG_Validity   (BOOL) TRUE if the output signal is valid,
  317.             otherwise FALSE. Most receivers do not react
  318.             if MTAG_Validity is FALSE.
  319.  
  320.     MTAG_ResetUDB   If this tag occures, UDBs are reset and will
  321.             not be put out any more.
  322.  
  323.     MTAG_ResetLSA   This tag clears the local sample address which
  324.             is used in studio mode transfers only.
  325.  
  326.  
  327.    NOTES
  328.     Note that MTAG_Rate will only be transmitted in the channel
  329.     status bits and is completely independent to the rate that
  330.     Maestro uses for data transfer. Maestro is only capable to
  331.     generate a 48kHz rate (INPUT_SRC48K). If another rate is
  332.     required, it must be put to the choosen input.
  333.  
  334.     Some receivers do not accept the incoming signal if the
  335.     transmitted rate is not equal to the transfer rate.
  336.  
  337.     This function must be used from DOS process only!
  338.  
  339.    SEE ALSO
  340.  
  341.    BUGS
  342. maestix.library/StartRealtime                   maestix.library/StartRealtime
  343.  
  344.    NAME
  345.     StartRealtime -- Starts realtime FX (V38)
  346.  
  347.    SYNOPSIS
  348.     StartRealtime (^MaestroBase, ^Tags)
  349.                A0.l       A1.l
  350.  
  351.    FUNCTION
  352.     This function starts a realtime effect. Before that, the used
  353.     input and OUTPUT_FIFO should be selected.
  354.  
  355.    INPUTS
  356.     MaestroBase     Pointer to MaestroBase Struct from AllocMaestro().
  357.     Tags            Tag list with the effect parameter
  358.  
  359.    RESULTS
  360.  
  361.    TAGS
  362.     MTAG_Effect     Selects one of the internal effects (default:
  363.             RFX_Bypass). See include file for all available
  364.             effects.
  365.     MTAG_A0         Effect parameter
  366.     MTAG_A1         Effect parameter
  367.     MTAG_D2         Effect parameter
  368.     MTAG_D3         Effect parameter
  369.     MTAG_CustomCall (APTR) Pointer to a custom effect routine.
  370.  
  371.    NOTES
  372.     The custom effect routine gets the following parameters:
  373.  
  374.         -> D0 (WORD)    left data word
  375.         -> D1 (WORD)    right data word
  376.         -> D2 (ULONG)   see MTAG_D2
  377.         -> D3 (ULONG)   see MTAG_D3
  378.         -> D6 (ULONG)   scratch
  379.         -> D7 (ULONG)   scratch
  380.         -> A0 (ULONG)   see MTAG_A0
  381.         -> A1 (ULONG)   see MTAG_A1
  382.         -> A2 (APTR)    return address
  383.  
  384.     The routine's results are:
  385.  
  386.         <- D0 (WORD)    new left data word
  387.         <- D1 (WORD)    new right data word
  388.  
  389.     The register D2 to D5 and A0 to A7 must not be changed!
  390.  
  391.     Use "JMP (A2)" to return from the effect routine. Don't use RTS.
  392.  
  393.     The effect routine must be in MEMF_PUBLIC memory. Note that a task
  394.     must not be necessarily in MEMF_PUBLIC memory! This routine should
  395.     be coded in high optimized assembly language.
  396.  
  397.     If the effect routine is too slow on the used processor, this
  398.     function will be stopped automatically, and MSTAT_TFIFO and
  399.     MSTAT_RFIFO result FIFO_Error.
  400.  
  401.    SEE ALSO
  402.     StopRealtime()
  403.  
  404.    BUGS
  405. maestix.library/StopRealtime                     maestix.library/StopRealtime
  406.  
  407.    NAME
  408.     StopRealtime -- Stops the realtime FX (V38)
  409.  
  410.    SYNOPSIS
  411.     StopRealtime (^MaestroBase)
  412.               A0.l
  413.  
  414.    FUNCTION
  415.     This function stops a realtime effect.
  416.  
  417.    INPUTS
  418.     MaestroBase     Pointer to MaestroBase Struct from AllocMaestro().
  419.  
  420.    RESULTS
  421.  
  422.    NOTES
  423.     Before using TransmitData() or ReceiveData(), a currently running
  424.     realtime effect must be stopped by this function!
  425.  
  426.    SEE ALSO
  427.     StartRealtime()
  428.  
  429.    BUGS
  430. maestix.library/TransmitData                     maestix.library/TransmitData
  431.  
  432.    NAME
  433.     TransmitData -- Transmits data from a message (V35)
  434.  
  435.    SYNOPSIS
  436.     TransmitData (^MaestroBase, ^Message)
  437.               A0.l         A1.l
  438.  
  439.    FUNCTION
  440.     The client has to fill out a DataMessage structure with a
  441.     reply port, a pointer to a data buffer and the size of this
  442.     buffer.
  443.  
  444.     This message is queued internally. If the transmitter has not
  445.     been started yet, this function will activate it.
  446.  
  447.     The buffer space will be put out and then be replied to the
  448.     declared reply port.
  449.  
  450.     If there are no more messages in the queue, the transmitter
  451.     will be stopped automatically, and an error is reported.
  452.  
  453.     The buffer contains signed words. The first word always belongs
  454.     to the left channel, the second to the right, and so on.
  455.  
  456.    INPUTS
  457.     MaestroBase     Pointer to MaestroBase Struct from AllocMaestro().
  458.     Message         Pointer to a system message with a pointer to
  459.             a buffer space for incoming data.
  460.  
  461.    RESULTS
  462.  
  463.    NOTES
  464.     The buffer space must be public memory. Its address must be
  465.     longword aligned and its length must be aligned to 1024.
  466.  
  467.    SEE ALSO
  468.     ReceiveData(), FlushTransmit()
  469.  
  470.    BUGS
  471.  
  472.